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INTRODUCTION 

File A file is a logical unit of data composed of a collection of 

, records. The principal external devices available for storing 
files are: 

• Disk devices (for example, diskettes, cartridge disks, 
cartridge module disks, fixed (sealed) disks, and mass 
storage units) 

• Magnetic tape units (for example, 1/2-inch tapes and 
1/4-inch cartridge tapes). 

Volume The media residing on the external devices ar^ referred to as 

volumes (for example, disk volume, tape volume). 

Various conventions have been established to identify and locate 
files stored on disk and magnetic tape. These conventions 
facilitate the orderly and efficient use of the data stored on 
the volumes. 

Unit Record Unit record devices (such as card readers, card punches, 
Devices printers, and terrrinals) also use the file concepts. However, 

since unit record devices cannot be used to store files, there 
is less need to establish conventions for identification and 
location. A unit record file is simply the data that is read or 
written at any one time (for example, a line entered at a 
terminal) . 

DISK FILE CONVENTIONS 

You must be able to specify an access path to any given file on 
a disk volume that contains multiple files. Files must 
therefore be organized on the volume in some predictable 
fashion. The File System provides a set of volume organization 
conventions by which the system can locate any element that 
resides on the volume. 

The principle elements of this organization, aside from the 
files themselves, are directories. The access path to any given 
element on a volume Is known as & pathname. 
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Directories 



Files on disk: devices are logically arranged by the File System 
in a tree-structured hierarchy. The basic elements of this 
hierarchy -are special files known as directories. The 
directories are used to point to the location of data files, 
which are the endpoints of the tree structure. 

A directory on a disk volume is an index that contains the names 
and starting locations (sector numbers on the volume) of files 
or other directories (or both). The elements in the directory 
are said to be "contained in" or "subordinate to" the 
directory. Therefore, tne organization of a disk volume is a 
multilevel structure. Tne complexity of the access path to any 
given element in the structure depends on the number of 
directories between the root and the desired element. 

A sample directory structure is illustrated in Figure 2-1. The 
base directory on a volume is termed a root directory. In 
Figure 2-1 the root directory is V0LC1. Root directory VOL01 
contains two subordinate directories, 01R1 and DIR2. 
Directories DIR1 and DIR2, in turn, contain data files FILEA, 
FILEB, FILEC, anc FILED, 

The root directory and other special types of directories are 
described in the following paragraphs. 
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Figure 2-1. Example of Disk Directory Structure 
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Root Directory 



The File System maintains a tree structure for each disk mounted 
at any given time. At the base of each tree structure is a 
directory known as the root directory. This is the directory 
that ultimately contains every element that resides on the 
volume, either immediately or Indirectly subordinate to it. The 
root directory name is the same as the volume identifier of the 
volume on which it resides. The directory VOL01 in Figure 2-1 
is the root directory on the disk volume VOL01. 



System Root Directory 



One or more disk root directories can be known to the system at 
any time during its operation. One of these, the System Root 
Directory (SRD), is required at all times. The absolute access 
paths of files In the SRD can start with two greater-than signs 
{>>). The volume used by the operator to initialize the system 
establishes the SRD. The boot volume must contain the SRD; it 
also normally contains system programs, commands, and other 
routinely used elements. The SRD must contain a number of 
directories and files that the system needs to perform its 
functions, including Z3EXECUTIVEL, SID, AID, HIS, and USER.REG. 
For more information, refer to the System Building and 
Administration manual • 



User Root Directory 



The File System can recognize one User Root Directory (URD), 
which you define through the Change System Directories command 
with the -ROOT argument. Files in the URD can have absolute 
access paths that start with a single "greater-than" character. 
The URD contains items such as UDD, LDD, MOD, FORMS, PROGS, and 
TRANS. For more information, refer to the System Building and 
Administration manual . 

The URD and SRD can reside on different volumes or on the same 
volume. The installation can also have user volumes created to 
meet the installation's own particular needs. These volumes may 
contain user application programs and their associatec data 
files, application program source and object code files, listing 
files, and anything else a user might want to store temporarily 
or permanently. 

Refer to "Links" later in this section for information on 
another way to distribute software (system or user) onto more 
than one volume. 
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Intermediate Directories 



When you first create (format and name) a volume jnder the File 
System, it contains only a root directory. Within this 
cirectory, you car create any aadtlonal directories required to 
satisfy trie needs cf the instal lation. 

Consider, for example, a volume that is tc contain data used by 
two amplication projects, each of which has several users 
associated with it. Each user has one or more files cf interest 
to him or her. The volume has been initialized and certains a 
root cirectory name. Two directories can be created subordinate 
to the root directory, each identified by the project name, 
"hen, subordinate to these directories, a directory can be 
created for each user associated with each project. 

The data files are all contained within the personal 
directories. This sample directory structure is illustrated in 
F ; gure 2-2. 
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Figure 2-2. Sample Directory Structure 



Deleting When the need for a user-created cirectory no longer exists, the 

Directories directory can oe deleted from the File System (deleted from the 
disk). The space it occupies, as well as the space occupied by 
its attributes in the i mediately superior directory, is then 
available for reuse. A directory must be empty before it can be 
deletea. All cirectories and files subordinate to the one to be 
deleted must have been previously de'eted by explicit commands. 
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Working Directory 



The File System always starts at a root directory when it 
searches for a disk file or a directory. At times the search 
for an element residing on a disk volume may traverse a number 
of intermediate directory levels before the desired element is 
located, and the File System must be supplied with the names of 
all the directories it must pass on the way. 

Frequently all files of interest to a user doing work on the 
system are contained in a single directory that is three or four 
levels deep in the hierarchy. It is convenient to be able to 
refer to files in relation to a directory at some arbitrary 
level in the hierarchy rather than in relation to the root 
directory. The File System allows this to be done by 
recognizing a special kind of directory known as a working 
directory. 

A working directory establishes a reference point that enables 
you to specify the name of a file or another directory in terms 
of Its position relative to the working directory. If the 
access path of the working directory is made known to the File 
System, arc if the desired element is contained in that 
directory, the element can be specified by just its name. The 
File System concatenates this name with the names of the 
elements of the working .directory's access path to form the 
complete access path to the element. 



Disk Directory and File Locations 



The File System has total control over the physical location of 
space allocated to directories and files. Vou need never be 
concerned about where a directory or file resides on a volume. 
When a volume is first initialized, space is allocated to 
elements in essentially the order in which they are created. 
But, after the volume has been in use for some time, elements 
may have been deleted and the space they occupied made 
reusable. Then, when a new element is created, it is allocated 
the first available space. If more space is needed, it is 
obtained from the next free area. 
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Disk Directory and File Naming Conventions 



Allowable 
Characters 



Characters 
CO-FE 



Uppercase 

and 

Lowercase 



Form-nc 
Names 



Each disk directory and file name in the File System can consist 
of the following American Standard Code for Information 
Interchange (ASCII) characters: 

• Uppercase and lowercase primary character set alphabetics 
(A-Z, a-z) 

• Digits (0-9) 

• Underscore (_) 

• Hyphen (-) 

• Period (.) 

• Apostrophe ( ') 

• Uppercase and lowercase characters whose hexadecimal 
equivalents are from CO-FE (Western European Latin alphabet, 
also called the extended character set). 

The characters in the extended character set cannot be used in 
volume identifiers. 

If the terminal is not capable of processing 8-b1t data, 
characters from the extended character set are displayed as 
periods or as their 7-bit equivalents. 

When volumes, files, and directories are created, their 
identifiers are stored on disk exactly as entered, 1n uppercase 
and lowercase characters. For both the primary and extended 
character sets, the system considers uppercase and lowercase 
characters to be equivalent (for example, "DATA", "Data", and 
"data" all refer to the same file). 

The first character of any name must not be the character FF 

Jhexacecimal ) . The uncerscore character can be used to jo-n two 
or more words that are to be interpreted as a single name (for 
example, DATEJTIME). The period character and one or more 
following alphabetic or numeric characters are normally 
interpreted as a suffix to a file name. This convention is 
followed, for example, by a compiler when it generates a file 
that is to be listed. The compiler identifies this file by 
creating a name of the form FILEA.L. 
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Naire Length The name of a root directory (the volume identifier) can be from 
one through six characters in length. The names of other 
directories and files can be from 1 through 12 characters in 
length. The length of a file name must be such that any 
system-supplied suffix does not result in a name containing more 
than 12 characters. 

Unique Names Within the system at any given time, the access path to ever^ 

element must be unique. This requirement leads to the following 
rules for naming files: 

• Only one volume with a given volume identifier can be 
mounted at any given time. (The system notifies you of an 
attempt to mount a volume having the same name as one 
already mounted.) 

• Within a given directory, every immediately subordinate 
directory or file name must be unique. (The Create 
Directory and Create File commands notify you of an attempt 
to add a duplicate name.) 

Note that uppercase/lowercase differences do not constitute 
uniqueness. As previously mentioned, "DATA", "Data", and "data" 
all refer to the same file. 



Pathnames 



Length 



The access path to any File System entity (directory or file) 
begins with a root directory name and proceeds through zero or 
more subdirectory levels to the desired entity. The series of 
directory names (and a file name if a file is the target entity) 
is known as the entity's pathname. The construction of a 
pathname is described below. 



The total length of any pathname, including all symb 
exceed 57 characters. A working directory pathname, 
cannot exceed 44 characters. 



... . M „ ... 3 . ., ..-ol s, cannot 
rectory pathname, however, 



The last (or only) element 
entity upon which action is 
device name, directory name 
function to be performed* 
corrmand a pathname specifie 
created. The last element 
the command as a directory 
name are names of superior 
analogous situation occurs 
that in this case the final 
file to be created. 



in a pathname is the name of the 
to be taken. This element can be a 
, or file name, depending on the 
For example, in' the Create Directory 
s the name of a directory to be 
of this pathname is Interpreted by 
name; any names preceding the final 
directories leading to it. An 
in the Create File command, except 
pathname element is the name of a 
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Symbols Used in Pathnames 

The following paragraohs describe the symbols used to con-struct 

patinames. 

A circumflex (") 15 used at the beginning of a pathname to 
identify the name of a disk volume root directory (for example, 
"V0L011). 

**> A circumflex preceding a "greater-than" sign (~>) is used at the 

beginning of a pathname to identify the root directory of the 

current working directory (for example, ~>DIR1>FILEA is 

equivalent to ~VOL011>DIR1>FIIEA if the current working 
directory is on VOLOIL). 

> A "greater-than" sign (>) is used at the beginning of a pathname 

and between the names in a pathname. 

>name When used at the beginning of a pathname, the element whose name 

follows the > symbol is immediately subordinate to the root 
directory of the user-root volume (it resides under the URD) . 
Honeywell Bull supplied programs assume the URD contains the 
UDD, LDD, FORMS, MDD, PROGS, and TRANS directories. 

The correct way to refer to a directory in the URO is to precede 
the directory name by one "greater-than" sign (for example 
>UD0}. 

name>name When used between names in a pathname the > symbol indicates 

movement in the hierarchy away from the root directory. The 
symbol is used to connect two directory names or a directory 
name and a file name. Each occurrence of the > symbol denotes a 
chance of one hierarchical level. Trie element to the right of 
the symbol is immediately subordinate to the element on the 
left. 

Reading a pathname from left to right thus indicates movement 
through the tree structure in a direction away from the root 
directory. For example, if the root -"VOLOil contains a 
directory named DIM, the pathname of DIM is *V0L011>0IR1. If 
the directory named DIR1 in turn contains a file named FILEA, 
the pathname of FILEA 1s A VOL011>DJR1>FILEA 
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» 



Two consecutive "greater-than" signs (») are used at the begin- 
ning of a pathname to $pecify entities that are subordinate to 
the SRD. Honeywell Bull supplied programs assume the SRD con- 
tains the Z3EXECUTIVEL, SID, AID, HIS, and USER.REG directories. 

The correct way to refer to a directory 1n the SRD 1s to precede 
the directory name by two "greater-than" signs (for example 
>>SID). 

SVSLIB1 and SYSLIB2 can reside in either the SRD or the URD. 

A "less-than" sign (<) Is used at the beginning of a pathname to 
indicate movement from the working directory toward the root 
directory. Consecutive symbols can be used to indicate changes 
of more than one level; each occurrence represents one level 
change. One or more "less-than" symbols may precede only a 
pathname that assumes a directory without actually referring to 
it explicitly. Such a pathname is called a relative pathname. 



space 



An ASCII space character (hexadecimal 20) is used to indicate 
the end of an encoded pathname in a program. When represented 
in memory, a pathname must end with a space character. 



Surma ry 



The use of these symbols at the beginning of a pathname can 
summarized as follows: 



be 



Symbol 


Meaning 


^volume 


Any volume or root directory 


~> 


Under root cf current working directory volume 


> 


Under URD root 


» 


Under SRD root 


< 


Movement away from current working directory 
toward volume root 
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Absolute and Relative Pathnames 

Full A full pathname is one that begins with a circumflex. A full 

Pathname pa tn name contains all necessary elements to describe a unique 

access path to a File System entity, regardless of the type and 
location of the device on which 1t resides or where your working 
or assumed directory is. You use a full pathname to locate 
directories and files that reside on a device other than that on 
which the system volume (the volume from which the system was 
initialized) is mounted. 

The File System uses a full pathname when referring to a 
directory or file. However, it is frequently unnecessary for 
you to specify all of these elements- The File System can 
supply some of them when the missing elements are known to it 
and the abbreviated pathname is used in the appropriate 
context. An understanding of these conditions and contexts 
requires an understanding of absolute and relative pathnames. 

Aosolute . An absolute pathname is one that begins with a circumflex (*) 

Pathname or one or more "greater-than" symbols (>). 



If an absolute pathname begins with a 
pathname. 



ci rcumf lex, it is a full 



If an absolute pathname begins with one 
the first element named in the pathname 
immediately subordinate to the URD. 



"greater-than" symbol, 
is assumed to be 



If the pathname begins with two "greater-than" symbols, the 
first element named in the pathname is assumed to be directly 
subordinate to the SRD. 

Relative A relative pathname is a shortened version of the absolute 

Pathname pathname and assumes the working directory (or a higher 

directory in the structure) without explicitly referring to it. 
A relative pathname is one that begins either with a file or 
directory name or with one or more M less-than" symbols. 

If the pathname begins with a name (for example, DIR1>FILEA or 
FILES), the name (DIR1 or FILEB) is Immediately subordinate to 
the working directory. 



If a relative pathname begins with a "less-than" symbol (for 
example, <F0STER), the name following the "less-than" symbol 
identifies an element that is immediately subordinate not to 
working directory, but to the directory to which the working 
directory is immediately subordinate. If the pathname begins 
with two "less-than" symbols (for example, «APP2), APP2 1s 
immediately subordinate to a directory two levels higher than 
the working directory. 



the 
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A relative pathname contains one or more names. If it contains 
more than one name, each name except the last must be a 
directory name, the first being immediately subordinate to the 
current working directory level (or to a higher level, as 
specified by one or more M less-than n symbols), the second 
immediately subordinate to the first, and so on. The last or 
only name can be a directory name or a file name, depending on 
the function being performed. 

Simple A simple pathname is a special case of the relative pathname. 

Pathname A simple pathname consists of only one name: the name of the 

desired element that is Immediately subordinate to the working 

or assumed directory. 

You can refer to a file or directory that is on the same volume 
(but not subordinate to the working directory) by using an 
absolute pathname or by using any of the described forms of a 
relative pathname. 

Figure 2-3 shows some relative pathnames and the full pathnames 
they represent when the working directory pathname is 
>PR0J1>USERA. 
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BOX NUMBER 

1 

2 

4 

5 



RELATIVE PATHNAME 3 

DELTA 

OLD> DELTA 

<USERB>ALPHA 

< <PROJ2>USeRA>0€ LTA 

< 



3R0J1 



USERA 3 



LSERB 



DELTA 



ALPHA 



old 



DELTA 



FULLPATHNAt/E 

A SYS01 >PRCJ1 >USERA>DELTA 
A SYS01>PROJ1 >USERA>0LD>OELTA 

■ v SYSai>PRCJ1>L l SER6>ALPHA 
" l SYS01>PRCJ2>USERA>DELTA 
A SYS01>PROJ1 



SYSOl 




PPQJ2 



USERA 



DE-TA 



•ASSUME CURRENT WORKING D I RECTOR V IS *SY901 -'PROJ1 >USERA. 



84-ai9 



Figure 2-3. Sample Pathnames 
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Disk Device Pathname Construction 

A special pathname convention is used to specify an entire disk 
volume. (This pathname convention is typically used in volume 
copy, create, and dump requests.) The special pathname consists 
of an exclamation point (!) followed by the symbolic device name 
and, optionally, the name of the disk volume. The general form 
of the disk device pathname is: 

!dev_name[>vol_id] 

where dev_name is tne symbolic device name defined for the disk 
device at system building time, and vol.id is the File System 
name of the disk volume, without the circumflex (for example: 
»MSMOO>VOL01). 

Exclusive If the vol_1d 1s not supplied, reservation of the disk is 

Reservation exclusive (meaning that the reserving taste group has read and 
write access but other users are not allowed to share the 
volume). This pathname form is used when a new volume is being 
created. 

Read/Share If the vol_id is specified, reservation is read/share (meaning 
Reservation that the reserving task group has read access only, other users 
may read and write). This pathname form is used when copying a 
volume, when referencing the system volume, or when dumping 
selected portions of a volume without regard for the 
hierarchical File System tree structure. 
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Links 



Links are names you create through the Link Name command to 
refer to files anc directories in other volumes or directories 
as if they were in your wording directory (or any other 
specified directory"). Instead of :opy ; nc a file from one 
directory to another, you can link to it- You can also link to 
devices or to other links. 

For example, once you have established a link between the name A 
(in a given directory) and the pathname "VOLID>MYDIR>MYFILE, you 
can perform file operations using the link-name A as if it were 
the pathname. Instead of having to issue the command: 

MFA ~V0LID>MYD1R>MYFUE -RECOVER 

you can issue the corrmand: 

MFA A -RECOVER 

(Assuming you have defined A as a link-name in your current 
working directory,) 

For additional information concerning the Link Name and Unlink 
Name commands, refer to the Conuiands manual. 



Automatic Disk Volume Recognition 



The automatic volume recognition facility dynamically notes the 
mounting of a disk volume- This feature allows the File System 
to record the root directory name in a device table. All 
references to disk files and directories begin, explicitly or 
implicitly, with a root directory name; therefore, every mounted 
file is automatically accessible to the File System software. 



Disk File Comments 



You can include a comment as a file attribute when creating or 
modifying a file, directory, or index. A file comnent can range 
from 1 to 72 ASCII characters in length, surrounded by quotes. 
The List Names (LS) and Peruse Directory (PD) commands display 
comments. You create or revise a comment with the -COMMENT 
argument of the Create File (CR), Create Index (CX), Create 
Directory (CD), Modify File Attributes (MFA), or Modify 
Directory Attributes (MDA) command. 

You can allow multiple comments to be applied to a single file 
by assigning a record type to a file comment with the 
-COMMENT.TYPE argument of the above commands. 
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Disk File Organiration 



Since no one disk file organization can meet the needs of all 
users at all times, the system supports several different 
organizations, each of which is well suited to a particular 
application. Most of the supported organizations are based on 
the concept of a control interval (a unit of transfer between 
memory and disk) and are referred to as Unified File Access 
System (UFAS) files. UFAS file organizations provide file 
processing compatibility with other Honeywell Bull systems. 

You establish the organization of a data file when you create 
the file through the Create File command or program call. You 
read and write the file using commands, statements, and 
macrccalls provided by the compilers and Assembler. 

The following paragraphs summarize the disk file organizations 
Refer to the Data File Organizations and Formats manual for 
detailed descriptions of each organization. 



UFAS Sequential Disk File Organization 



Logical records are normally read from or written to a 
sequential file in consecutive order. Records must be written 
sequentially although the file can be positioned for writing 
through the use of a simple key. Records can be read, modified, 
or deleted directly when you specify their exact control 
interval and record address (simple key). Records cannot be 
inserted; they can be appended to the end of a file. Fixed- or 
variable-length records can be used. If a record is deleted, 
the position it occupied cannot be reused. 



UFAS Relative Disk File Organization 



A relative disk file can contain fixed- or variable-length 
records. If variable-length records are used, they occupy 
fixed-length slots (and the size of the largest record must be 
specified). Both sequential and direct access are supported; in 
direct access, simple and relative keys can be used. A record 
can be updated (rewritten), deleted, or appended to the file. 
If a record is deleted, the position it occupied can be used for 
a new record. A file can be created directly if you specify 
relative record numbers in random sequence. 
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UPAS Indexed Disk File Organization 



In an indexed disk f'le organization each logical record 
contains a fixed-size key field that occupies a fixed position. 
Records are logically ordered by key value; tney can be accessed 
sequentially in. key sequence or directly by key value. Fixed- 
or variable-length records can be used. Var-abl e-length records 
occupy variable-length slots. A record can be updated, deleted, 
or inserted in Key sequence into available free space. When no 
space is available to insert a record in key sequence, the 
record is placed in an overflow area. When the file is 
initially loaded, the records must be supplied in sequence by 
key value. 



UFAS Random Disk File Organization 



In a random disk file organization records are accessed directly 
or sequentially. Variable-length records occupy variable-length 
slots. Direct access of recorcs is perforrnec through CALC keys, 
which are fixed in size and located within each record- Records 
are positioned according to a technique involving an arithmetic 
derivation of their CALC keys, "his derivation is called a" 
hashing algorithm (and is carried out by the system). 
Insertions, updates, anc deletions are handled according to key 
value. When the file is initially loaded, records can be 
supplied in random key vaiue sequence* 



UFAS Dynamic Disk File Organization 



A dynamic disk file can contain fixed- or variable-length 
records and supports inventory informatior to describe available. 
space. The main purpose of this file organization is to provide 
an efficient storage organization fcr records tc be accessec 
through alternate indexes (explained below). Records are 
accessed sequentially or directly. Variable- length records 
occupy variable-length slots. Records can be accessed 
■ndlrectly through alternate indexes or directly by soecifying 
their exact control interval and record address (simple key). 
Records are inserted into the file according to inventory 
information on a "best fit 1 ' bas^s. When the file is Initially 
leaded, records can be supplied In ranaom key value sequence. 
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Non-UFAS Relative Disk File Organizations 

Non-UFAS relative disk file organizations are not compatible 
with other Honeywell Bull systems. These file organizations 
have fewer functional capabilities than UFAS files but require 
little or no space overhead. The non-UFAS file organizations 
are fixed relative and string relative. 

Fixed A fixed relative disk file can contain only fixed-length 

Relative records. All records in the file are considered active; the 

file cannot contain deletable records. A fixed relative file 
can be accessed directly or sequentially. New records can be 
inserted anywhere in the file. 

String A string relative disk file can contain variable-length 

Relative records. All records in the file are considered active. A 

string relative file can be accessed directly or sequentially. 

The ASCII line feed character (hex OA) is automatically appended 

to the end of each record. 

A DOS compatible string relative file is also available. It 
supports all the capabilities of a standard string relative 
file, but includes the ASCII carriage return and line feed 
characters (hex OAOD) at the end of each record. 



Pipes 



A pipe is a special kind of UFAS sequential file that is used 
for synchronizing and passing information among multiple 
cooperating tasks. Pipes are accessed (Reserved, Opened, Read, 
Written, Closed, and Removed) just as in any other sequential 
file. Pipes provide a synchronization and queuing facility, and 
offer a convenient way of organizing and distributing work. 

One or more tasks write into the pipe while others read from 
it. If the pipe is empty but open for writing, Read reauests 
are suspended until data (a logical record) is available. A 
Read implicitly deletes the logical record just read from the 
pipe. When the pipe is empty and no longer open for writing. 
Read actions return the normal end-of-file status. 
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Alternate Indexes 

Alternate indexes allow you to define any number of alternate 
record <eys to provide any number of different logical orderings 
of keyed records within a single disk file.. In effect, 
alternate indexes provide different orderings (views) of the 
same data. The same data file can be viewed in many different 
ways by having more than one alternate index. For example, an 
application could have a UFAS relative file containing employee 
information with alternate indexes for employee numbers, 
employee names, and social security numbers- You could access 
such 2 file as a relative fie, as an indexed file ordered by 
employee numbers, as an indexed file ordered by employee names, 
or as an indexed file ordered by social security numbers. 

File Types The alternate index capability exists in addition to the normal 
access node basea on type of file. You can establish an 
alternate index for any UFAS relative, indexed, random, or 
dynamic disk file. 

Access A file with more than one index can be accessed in a number of 

ways. The manner in which the file is reserved (through the Get 
File command) determines how the file is accessed. If the data 
file itself is reserved, the file can be accessed normally 
(according to file organization) or oy a key that is supported 
by one of tne indexes. When the data file is reserved through 
an alternate index, the contents of the file can be accessed as 
a standard indexed file. 

Indexes as Adcitional ly, if more than one index exists, the indexes can be 
Keys usee as alternate keys to refer to the data* When an alternate 

index is used for f^le reservation, that index is used as the 
primary key. The remaining indexes can be used as alternate 
keys. Any inaex can be selected as a primary index. When one 
index is used to access the file, it and the other indexes are 
automatically updated as the file is updated. 

Dynamic UFAS dynamic disk files contain inventory information to manage 

files available lie space. Therefore, in highly volatile file 

environments that include many insert and delete operations, 
cynamic disk files are the ideal data files to be used with 
alternate inaexes. 

Key Types Character string, signed binary, signed unpacked decimal, and 

signed or unsigned packed decimal key types can be used- Single 
component keys, ordered in ascending or descending sequence, are 
supported. Duplicate keys (more than one record in a file with 
the same key value) are supported on an index-by-index basis. 
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Index An alternate index is created with the Create Index command. 

Creation Arguments of this command specify the name of the index and the 

name of trie data file with which it is to be associated. The 
system creates the index on the same directory as the data file 
aod, unless otherwise specified, with the same control interval 
size as that of the data file. 

Refer to the Data File Organizations and Formats manual for 
further information. 



Disk File Structure 

A disk file is a logical unit of data composed of a collection 
of records. The unit of transfer between memory and disk 1s 
called a control interval. 

Record A record is a user-created collection of logically related data 

fields. Records are treated as units and can be fixed or 
variable in length. 

Control A control interval is the unit that is transferred between 

Interval memory and disk. The size of a control interval is user- 

specified (a multiple of 256 bytes) and remains constant for the 
file. A UFAS file is composed of control intervals that are 
numbered, starting at one. The control interval also determines 
the buffer size (which must be a multiple. of the control 
interval size). 

Disk File Protection 

The File System provides facilities that enable you to control 
the access to files and directories, to control the concurrent 
access to files, and to control the contention for records 
within shared files. 
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Access Control 

Access control is an optional File System feature that allows 
Che creator of a file or d ; rectory to specify which users (If 
any) are tc be granted access to the £ ile or directory and what 
types of access these users are to be granted. 

There are two general forms of access control: Access Control 
Lists (ACLs) and Common Access Control Lists (CACLs). ACLs 
apply directly to a file or directory; CACLs apply eoually to 
all irrmediately subordinate entries in a directory. Entries in 
the ACLs and CACLs are managed through Set Access. Delete 
Access, and List Access commands. 

Access control is a file or directory attribute. The File 
System maintains :n each directory a list o"f users and the type 
of access each user 1s allowed. If a directory does not contain 
sucn a list, the items contained within it are not protected and 
are accessible :o all users. (Access control applies only to 
disk files and directories. Tape files and other device-type 
files such as terminals and card readers cannot be protected 
through the access control facility.) 

File Access Access tyoes for files are reaa, write, and execute. These 
Types access types allow the following operations: 

• Read: Peruse, a fi.le, but not change it. 

• Write: Read, modify, create, or delete a file. 

• Execute: Execute a program. 

Directory Access types for directories are list, modify, and create. 

Access Types These access types allow the following operations: 



List: List the contents cf a directory. 



• Modify: Modify the contents of a file in a directory, but 
not create or delete a file. 

• Create: List, modify, create, or delete files and 
subdirectories in the directory. 

A null access type apolies to both files and directories. Nul 
access indicates that no access is to be granted. 
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User Id Access control assumes that access to the system is controlled 

by a login process in which every user has a unique user id. 
This user id is composed of three elements that are specified at 
login and that remain unchanged during the time the user is 
logged in. The three elements are: 

person .account .mode 

person 

Name of individual who may access the system, 
account 

Name of account to which wo"k is charged. 

node 

Further identification of the user (optional). Can name 
the mode in which the user is working (for example, 
interactive, absentee, or operator). 

The elements of the user id can consist only of the ASCII 
uppercase and lowercase alphabetic characters (A-Z, a-z), digits 
(0-9), underscores (_) , dollar signs ($) , apostrophes (') and 
trie uppercase and lowercase graphics whose hexadecimal 
equivalents are CC-FE (extended character set). Apostrophes and 
the characters whose hexadecimal equivalents are CO-FE can be 
used only in the person and account elements. For Doth the 
primary and extended character sets, uppercase and lowercase 
characters are equivalent (for example, JOHN. SYSTEM. AB is the 
same user id as JohN.sySTEM.ab). 

The elements are separatee with periods (.)• When referencing 
user ids, you can replace any or all elements by asterisks (*); 
for example: 

*. account. mode 

person. account.* 
* * * 

When an asterisk appears in an element position, it is 
interpreted to mean any value that may exist. No test is 
performed to match this element of the user id. For example, if 
two persons (Smith and Jones) are registered in an account named 
FILE_5YS, the user id *.FILE_SYS.* matches either person in any 
possib'e mode. (The user id *.FIl_E_SYS.* matches all 
individuals registered to use FIlE_SYS in any mode.) 
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Access There are four kinds of access control lists: file ACLs, 

Control directory ACLs, file CACLs, and directory CACLs.Usts list 

rile ACL A file ACL is a type of access control list that applies to a 

specific file and is considered to be a file attribute. It 
contains a- list of tnose users who can access the file and their 
specific access rights (Reac, Write, Execute). 

Directory A directory ACL is a type of access control list that applies 

ACL to a sDecific directory and is considered to be a directory 

attribute. It contains a list of tnose users who car access the 
directory and their specific access rights (List, Mocify, 
Create) . 

Fi 1e CACL A file CACL is a type of access control list that applies to all 

files immediately subordinate to a directory, A file CACL" is 
considered to be a d : rectory attribute that applies orly to 
files contained in that directory. A file CACL contains a list 
of file users and their specific access rights (Read, Write, 
Execute). Use of file CACLs can save disk space and search t<me 
if all or most files m a directory have the same access 
requirements. A file CACL does not override individual file 
ACLs set on f'les in the directory. 

Directory A directory CACL is a type of access control list that applies 

CACL to all directories immediately subordinate to a directory. A 

directory CACL is considered to be a directory attribute that 
applies only to immediately subordinate directories. A 
directory CACL contains a list of directory users anc their 
soecific access rights (List, Modify, Create). Use cf directory 
CACLs can save disk space and search time when all or most 
subdirectories nave the same access requirements. A directory 
CACL does not override individual directory ACLs set on the 
suodirectories. 

The Create Directory command a' : ows a directory CACL tc be 
established as a global directory attribute. The directory CACL 
is automatically passed down to subsequently created subordinate 
directories. 

Checking When you reserve a file (through the Get File command or system 

Access " service macrocall), the File System checks your right to access 

R-gnts that file. You are said to be or the access control list if 

your user id matches an entry on the ACL or CACL in any of the 

forms noted below. 



2-24 C203-C2 



File Concepts 



Universal Universal access (no access restriction) is implied if neither 

Access an ACL nor a CACL exists for the file being reserved. If either 

list is present, it is scanned by access control. 

Priority The checking priority is ACL first, CACL second. If a match Is 

found in the ACL for a fully specified user id (all three 
elements explicitly stated), the CACL 1s not inspected. If a 
match is found on a partially specified user id (one or more 
elements specified as an asterisk), the CACL is inspected for a 
more explicitly stated user Id, The following list indicates 
the inspection hierarchy of user id formats in order of 
decreasing priority. For example, if you are granted access by 
an ACL entry in format 3, you can be denied access only by an 
ACL or CACL entry in format 1 or 2. 

1. oerson. account .mode 

2. person. account.* 

3. person.*. mode 

4. person.*.* 

5. *.account.mode 

6. *.account.* 

7. *.*.mode 

8. *.*.* 

Target File Access is checked only for the target file or directory; the 
Access access rights set on directories that may be traversed in 

reaching the target file are not checked. You may be denied 
access at some intermediate directory level and still gain 
access tc a subordinate directory or file. 



Operator Access 
Access accessi 
access 



control lists do not prevent the system operator from 
ing files and directories. It is suggested that physica 
to the operator terminal be restricted. 
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Fil# Concurrency Control 



Concur-ent Read or 
established by the 
Concurrency contrc 



Write use of a file among task groups is 
task group that first reserves the file- 
performs the following functions: 



• Establishes how tastes in the reserving task group intend to 
access the file (Read, Write, or Execute). 

• Establishes what the reserving task group allows other task 
groups to do with the file. 

File If the file is already reserved, a task group's concurrency 

Reservation request (reservation) is denied if its intended access conflicts 
with the access permitted by a prior reserver. The concurrency 
request is also denied if what it allows others to do conflicts 
with the access already established by another task group. For 
example, if a task group reserves the file exclusively, other 
task groups are denied access. If a task group permits 
read-only access but does not permit write access, other readers 
are allowed but writers are denied access. 

Get File Concurrency is controlled through the Get File conmand or system 

Comnand service macrocall. Tne possible combinations of access intended 

for the reserving tas< group and snarability permitted other 
task groups are given in Table 2-1. Table 2-1 also shows the 
Get File command arguments that establish the various 
concurrencies. 



Table 2-1. Disk File Concurrency Control 



Reserving 
Task Grcup 


Other Task Groups 


Get File Arguments 


Read only 


Read only (read share) 


-ACCESS R -SHARE R 




3ead or write 
(read/write share) 


-ACCESS R -SHARE W 


Read or write 


No read, no write 
(exclusive use) 


-ACCESS W -SHARE N 




Read only (read share) 


-ACCESS W -SHARE R 




Read or write 
(read/wnte share) 


-ACCE5S W -SHARE W 
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System Compiler-generated programs, commands, sort operations, and 

Concurrency other system software always request exclusive concurrency for 
files reserved for users. Since the operator terminal must be 
reserved with read/write shared concurrency to allow concurrent 
access by many task groups, it cannot be specified as the path 
of the -C0UT argument of a command that invokes a compiler. 

The command-in, user-1n, user-out, and error-out files are 
associated with the Menu Processor and Command Processor (refer 
to Section 3). If the command-in and user-in files are on disk, 
they are reserved with read-only shared concurrency: if assignee 
tc a user terminal, they are reserved with exclusive 
concurrency. You can use File Out commands to specify the 
concurrency with which the user-out and error-out files are to 
be reserved. 



Access Control/Concurrency Control Relationship 

In an environment that employs access control, users must have 
certain minimum types of access privilege to obtain the specific 
type of concurrency control they specify in Get File commands or 
system service roacrocalls. 

Table 2-2 summarizes the relationship between access control and 
concurrency control for disk files, disk directories, and disk 
volumes. (Note that access control does not exist for other 
types cf devices.) 



Table 2-2. Access Control /Concurrency Control Relationship 



Object 


Desi red Concurrency 


Minimu-n Access 


Disk files 


Read 
Read/write 


Read 

Read/write 


Disk directories 


Exclusive use 
Nonexclusive use 


List/modify 
List 


Disk volumes 


Read or read/write 


Modify access to root 
directory 
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Shared File Protection {Record Locking) 

Record locking is a File System option that provides 
interference protection so that cooperating users can share and 
update file data. For example, with record locking in effect 
there can be many task groups running COBOL applications that 
Read, Write, and Update record data in the same file or same set 
of files- 
Meed for User applications often employ standard data management services 
Locks to lock records as they access them. The purpose of the locks 
1s to prevent other users from simultaneously getting access to 
these records. If ether users coulc access che records, they 
might get information that is only partially updated or, as a 
result of some programming decision or error condition, nay soon 
be removed fron the file. Also, if there were no locks, two 
users could update the same records at the same time. In this 
situation the second updater would inadvertently remove any 
modifications made by the first updater. 

"or reasons such as these, record locking is a necessary feature 
in most file sharing environments. Moreover, in many file 
sharing environments it is important that more tnan one lock be 
simultaneously maintained- For example, an "update" transaction 
to a parts inventory file may involve multiple record updates-- 
subtracting 'rom some records and adding to others. These 
multiple record locks may even involve access to multiple files. 

Note that record locking is not necessary to prevent a file from 
being physically corruoted by several applications performing 
multiple writes. Whether or not record losing is present, the 
File System maintains indexes and record chains properly so that 
the file structure is consistent. However, without record 
locking there is no synchronization, and the file data can be 
logically corrupted by two or more users who update the same 
data records. Also, without record locking, data can be viewed 
in a partially updated or inconsistent state. 

Record The record-locking option provides synchronization mechanisms to 

Locking lock out record data as it is accessed, thereby making tne data 

Function inaccessible to other applications until it is explicitly 

unlocked via a cleanpoint call (a call to the ZCLEAN utility in 
higher-level languages, or $CLPNT macrocall in Assembly 
language) . 

Lock Lists The File System locks records by maintaining lists that describe 
which file control intervals are locked, who has them locked, 
and wno is waiting for them to be unlocked. 
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Deadlock The "lie System also provides a mechanism to recognize (and 

signal) whenever a deadlock condition occurs, A typical example 
of a aeadlock is when one user owns (has locked) record A and 
wants to lock record B while another user already has record B 
locked and is waiting for record A to be unlocked- 
Standard Two methods of "ecord locking are available. These are standard 
Locking record locking (-LOCK) and extended record locking (-L0CKX). 

With stanoard record locking, if a file is open to allow update 
operations, records are locked on an exclusive basis. Read, 
Write, Rewrite and Delete- record calls automatically lock the 
records accessed until they are explicitly unlocked with a 
cleanpoint call . 

Extended Extended record locking provides record locking on a shared-read 

Locking or exclusive-write basis, which allows many simultaneous readers 

but only one writer at a time. Readers will wait until a writer 
finishes (issues a cleanpoint call) and vice versa. Read-record 
operations set read locks; write-record, rewrite-record, and 
delete-record operations set write locks. 

Since, with extended record locking, the type of lock 1s 
determined dynamically at each access request rather than once 
at open time, more readers can access more file data at the same 
time. Using -LOCKX will improve performance if requests 
corrmonly involve reading or searching through large amounts of 
data. It is especially useful in situations which Involve few 
updates or update conflicts. 

Because readers can gain access to to records they can 
suosequently update, increasing the possibility of deadlock 
errors, extended record locking requires the -RECOVER argument 
(see "File Recovery" in Section 6). If two or more readers 
attempt to update the same data, -LOCKX can issue rollback calls 
to recover the file data to a known consistent state. 

To Set You can set standard record locking (-LOCK) or extended record 

Locking locking {-LOCKX] as a permanent file attribute when you create 

the file, with the Create File (CR) command, or modify its 
attributes, with the Modify File Attributes (MFA) command. You 
can also set standard record locking temporarily when you 
reserve the file for processing with the Get File (GET) 
command. You can change from locking tc no locking as a 
permanent file attribute with the -N0J.0CK or -N0J.0CKX argument 
of the MFA command. 
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Dirty A file having the -LOCK or -_OCKX attribute can be reserved 

3eade r without record locking through the -N0_LCCK argument of the Get 

"ile command. This is a special "Dirty Reader" option that lets 
you read aata even though the data may be locked or may oe in 
the process of being updated by seme other user. The 
consistency and integrity of any data read is not guaranteed. 
The "Dirty Reader" option is available only on a logical file 
number (LFN) basis. The associated IFN is read-only, ignores 
any existing record Iocks, and cannot set any locks. (LFNs are 
internal file identifiers associated with file pathnames at the 
command or source program level; refer to "Logical File Numbers" 
in Section 5 for further information.) 

No-Wait A file with the -LOCK or -LOCKX attribute can a^so be reserved 

ODtion with the No-Wait option through the -NC.WAIT argument of the Get 

rile command. If the No-Wait option is specified, the File 
System returns an error status rather than causing you to wait 
for a record to be unlocked. The No-walt option is available 
only on an LFN basis. 

Programming When using record locking, you should be aware of the following 
Hints points: 

• To efficiently use record locking, your applications must be 
written to be transaction-oriented so that records are not 
locked for a long period cf time (for example, while waiting 
for terminal I/O) and so that as few records as possible are 
locked to satisfy the request. 

• Vou should consider using other file integrity features 
(described in Section 6), especially file -ecovery, which 
allows data to be reset (rolled back) to the state it was in 
at the start of tne transaction. In many situations, file 
recovery is a necessary feature to maintain data integrity 
in the event of system failure, record deadlock, application 
failure, terminal failure, anc sd forth. 

• Tc cevelop an efficient multiuser application that shares 
and updates data in standard files, you must examine wnere 
and how the application is accessing file data and design 
the file structure carefully. En addit'on, you must pay 
careful attention to error conditions involving data 
recovery and program or transaction restarts. 

• Applications that receive a ceadlock notif-cation must oe 
prepared to bac* out cf the current "transaction" anc *ree 
up the locks they concurrently own. If the file is 
recoveraole, this is ocne through the rollback call (a call 
to the ZC30LL utility in higher-level languages; a IR.QLBK 
mecroca'l in Assembly language). 
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• When a record is locked, the entire control interval in 
which the record is contained becomes locked. When defining 
control interval size, you should consider not only I/O 
transfer size and memory buffer usage, but also the number 
of records that may be locked out. 

• If the No-Wait option is selected, central processor time 
must be given up so that other users who have the record 
locked get a chance to unlock it. You may need to add a 
"suspend for time interval" function to applications using 
the No-wait option to allow other task groups enough time to 
finish their I/O and unlock records (issue a cleanpoint 
call). 

• Closing a file, Issuing a cleanpoint call, or issuing a 
rollback call frees up all records locked by the task group 
since the last cleanpoint. If a task group abort occurs, 
the system issues a rollback call automatically as part of 
the task group cleanup process. Likewise, if a system 
'allure occurs, the operator will issue the Recover command 
after the system is restarted. When this command is issued, 
the File System (in effect) performs a rollback call for all 
task groups that were active at the time of the failure. 

Multivolume Disk Files 

In most applications a disk file resides on a single volume. 

However, there may be situations in which you want to extend a 

file over more than one physical volume. The need for 

multivolume files could arise from any of the following: 

• You want an endless sequential file capability similar to 

that available with magnetic tape. 

• You want to define a single file too large to be contained 
en one vol ume. 

• You want to improve access time to a file by spreading the 
file data over several volumes and/or separating the index 
portion of an indexed file from the data portion and placing 
the portions on separate volumes. 

File Section A multivolume file is treated as a collection of file sections. 
A file section is that part of the file that is contained on one 
volume. 

File Set A file set is all of the sections making up the multivolume 

file. 
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Multrvolume Sets 

A nu It 1 volume set is a d'sk -Hie that resides on more than one 
volume. A volume is identified as seing part of a multivolume 
set when the volume is created through the Create Volume 
command. 

Each multivolume set has a root volume (in which the set begins) 
and a number of additional volumes. All volumes that are part 
of the set are called members. 

The name of a multivolume set is incependent of the names of the 
volumes it contains. A volume is established as a member of a 
set when the set name and a sequential member number are 
specified at volume creation. The root volume is always member 

number 1. 

There are two types of multivolume sets: online and serial. 
Online multivolume sets are used for all nonsequential 
multivolume files. They may also be used for sequential 
multivolume files. Serial multivolume sets are an alternative 
for large sequential files. They are also used for files that 
reauire an endless sequential capability similar to that of 
magnetic tape. 

The types of multivolume sets and files are described in detail 
below. 

Online A vo'ume is designated as part of an online multivolume set at 

Multivolume volume creation. An online multivolume set has the following 
Set characteristics: 

• All members of the set must be mounted and available while 
the set is in use. 

• Member volumes, other than the root volume, can be used 
independently of other members in the set to contain 
single-volume files and directories. 

Online A file is designated an online multivolume file when it is 

Multivolume created under a directory in the root volume of an online 
File multivolume set. An online multivolume file has the following 

characteristics: 

• Can have any UFAS file organization. 

• Can be located by any type of pathname. 

• Can skip set members when continuing to another volume. 
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Figure 2-4 illustrates the combination of files and volumes used 
by a sample online mul tivolume set. Multivolume files FILEA, 
FILEB, and F3LEC must begin on VOL1 . FILEX, FILEY, and FILEZ 
are single-volume files because they do not begin on VOL1. The 
pathnames usee to access the files are shown at the bottom of 
the figure. 
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A V0L2>FILEB 
~V0L3>FILEC 
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MEMBER 
~V0L3>FILEX 
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^V0L4>F|LEY 

"V0L4>F|LEZ 
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Figure 2-4. Example of Online Multivolume Set 



Serial A volume is designated as part of a serial multivolume set at 

Multivolume volume creation. A serial multivolume set has the following 
Set characteristics: 

• No member of the set need be mounted until the data on it is 
required for processing. 

t Any member of the set. including the root volume, can be 
used independently of other members of the set to contain 
single-volume files and directories. 
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Serial A file is designated as a seria" multivolume file when it is 

Multi volume createc in the root directory of a volume in a serial 
File mult ; volume set. A serial multivolume file has the following 

characteristics: 

• Must be a UFAS sequential file. 

• Must be cataloged in the root directory of the volume on 
which it starts. More than one serial multivo'ume f i 1 e can 
belong to a set, and eacn such file can begin on a different 
volume if desired. 

• Wust be located through a pathname of the form 
*volid>f ilename. 

• Must continue serial ly from one volume to the next (cannot 
skip set members) . 

Figure 2-5 illustrates the combination of files and volumes used 
in a sample serial multivolume set. Serial multivolume file A 
begins in VOL1. Serial multivolume file B begins in V0L2. Both 
continue in other volumes of the set. Files C, D, and E a-e 
single-volume files. The pathnames by which the files are 
located are shown at the bottom of the figure. 
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Disk File Buffering 



A buffer is a memory storage area used to compensate for a 
difference in the rate of data flow, or time of occurrence of 
events, during transmission of data from one device to another. 
Buffering is the process of allocating and scheduling the use of 
buffers. In some applications, overlap of input operations and 
processing can be achieved by anticipatory buffering, where the 
next block of data is read into the program's memory area before 
It is needed. The program can then process records from block n 
while block n+1 is being read into the memory area. 



File Access Levels 



Buffer Pools 



Disk files can be processed at either block or record level. In 
block level access, data is transferred directly between the 
file and a Duffer in your program. Your program must perform 
all buffer management operations. In record level access, the 
system assigns disk files to buffer pools when your program 
opens the files. The system buffering facilities are used to 
perform all buffer management operations. 



When a file is opened for Read, Write, Rewrite, or Delete 
operations, the File System assigns the file to a particular 
buffer pool. A buffer pool is a collection of buffers that 
provides a method of conserving memory for disk file access. 
Buffer pools are designed to: 

• Reduce the amount of memory required for buffers by all 
users. 

• Recuce the number of I/O operations in a random access 
environment. 

• Provide more flexibility for shared file applications. 

All buffers in a pool are the same size. Any number of files 
with matching control interval sizes can be assigned to the same 
buffer pool. A particular file, however, can be assigned to 
only one pool . 

Each buffer in a buffer pool can store a disk control interval. 
When an application program issues a read instruction and the 
desired record 1s not 1n any Duffer in the buffer pool, the next 
empty bu'fe r in the pool is filled with the cortrol interval 
containing the record, when all buffers in the pool are filled, 
an active buffer is selected for the next different control 
interval according to a least-recent-usage algorithm. 
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In addition to conserving memory when disk files are accessed, 
buffer pools eliminate the need for each user to define private 
buffer areas. One or more system-wice buffer oools should oe 
created at system startup (through a startup EC file; see 
Section 3). Users who nave special buffering requirements can 
create thei r own buffer pools for files they reserve 
exclusively. 

Buffer Poo 1 Each buffer pool is created as either a public or a private 
Creation buffer pool, and can be considered file-specific or general. 

Buffer pools are createc by the Create Buffer Pool command and 
deleted by the Delete Buffer Poo' command. When creating a 
buffer pool, you specify the number of buffers it is to contain, 
the buffer size, and (optionally) the name of the buffer pool. 

Public Public buffer pools are those created by the operator or the 

=>ools system startup EC file. Public buffer pools reside in system 

memory anc are avaiiaole to all files and task groups. A disk 
file Is assigned to a public pool tf its control interval size 
(specified in the corrmand tnat creates the file) matches the 
pool ' s buffer size. 

In many environments, three or four public buffer pools 
corresponding to three or four common file control interval 
sizes are sufficient for all performance and buffering needs. 

If the system volume is associated with the disk cacne 
processor, heavily used directories, as well as files that are 
read sequentially, are likely to be resident in the disk cache 
buffer. Buffer pools for these directories and files may not be 

needed. 



Private Private buffer pools can be created by each user. Private 

Pools buffer pools -eside in the task group's memory space anc are 

available only for disk files reserved exclusively by that ^ask 
group. A disk file is assigned to a private pool if the file is 
reserved for exclusive use and its control interval size 
(specified in the conrcand that creates the file) matches the 
pool's buffer size. Private buffer pools should be created only 
if necessary to meet specific buffering needs. Public buffer 
pools should be sufficient in nost cases. 

File- When you reserve a disk file witn the Get File comnand, you can 

Specific specify the number of buffers (using the -BUF argument) to be 

Pools used when access'ng the file. When the file is opened, a buffer 

pool is automatically created for use only by that file. This 
file spec-fic pool is created in the task group's memory if the 
file is reserved exclusively, or in system memory if the file is 
reserved as shareable. The -BJF argument should be used 
carefully since it prevents a file from being assigned to a 
public or private buffer pool. 
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Buffer Pool The rile System collects a set of statistics on the use of each 
Optimizing buffer pool. The installation can use this informat-on to 
optimize disk I/O operations. Buffer pool statistics are 
obtained through the Buffer Pool Status and Buffer Pool 
Information commands. The Buffer Pool Status command provides a 
summary of the public or private buffer pool status- The Buffer 
Pool Information command provides a detailec status report on a 
particular buffer pool. 

The installation should analyze applications and their 
associated file usage to fully utilize the advantages offered by 
buffer pools. Only a limited number of control interval sizes 
should be allowed for user files. In general, buffer and 
control interval sizes should be chosen to evenly distribute 
high and low activity files over the various buffer pools, thus 
reducing the amount of contention in the pools. The initial 
determinations will provide an acceptable level of performance 
and provide the basis for further analysis. 

The Adjust Buffer Pool command can be used to temporarily alter 
the number of buffers in a private buffer pool. Once the most 
efficient buffer pool size has been established, it should be 
permanently fixed through the Create Buffer Pool (CBP) and 
Delete Buffer Pool (DBP) commands. In general, the system 
STAR7JJP.EC file should specify a CBP command for directory I/O, 
with the -DIR argument, and for space allocation, with the 
-ALLOC argument. Also include one or more CBP cormiands for 
commonly accessed disk files. This will result in higher 
performance, less system memory fragmentation and more memory 
available to users. This may require configuration cf a larger 
system memory pool and smaller user memory pools. 
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MAGNETIC TAPE FILE CONVENTIONS 



The magnetic tape file conventions discussed in the following 
paragraphs include file organization, naming conventions, 

pathnames, and buffering operations. 

Magnetic Tape File Organization 

The following information applies only to 1/2-inch, 9-track 
magnetic tapes. 

Magnetic tape supports only the sequential file organization. 
Fixed- C variab'e-length recorcs can te usee. Records cannot 
be inserted, deleted, or modified, but they can be appendec to 
the end of the file. The tape can be positioned forward or 
backward any number of records. 

Blocks The unit of transfer between memory and a tape file is a block. 

Block size varies depending on the number of records and whether 
the records are fixed or variable in length. 

A block xan be treated as one logical record called an 
"undefined" record. An undefined record is read or written 
without being blocked, unblocked, or otherwise altered by data 
management. Spanned records (those that span across two or more 
blocks) are supported. No record positioning is allowed with 
spanned records. 

Labeled A labeled tape is one that conforms to the current tape standard 

Tapes for volume and file laoels issued by the American National 

Standard Institute (ANSI). The following types of labeled tapes 

are supoortec: 

• Single-volume, single- file 

• Multivolume, single-file 

• Single-volume, multifile 

• Multivolume, multifile. 

Unlabeled The 'ollcwing types of unlabeled tapes are supported: 
Tapes 

• Single-volume, single-f^e 

• Single-volume, multifile. 
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Magnetic Tape File and Volume Names 

Allowable Each tape file and volume name In the File System can consist of 

Characters the following ASCII characters: Uppercase alphabetics (A 
through Z), lowercase alphabetics (a through 2), digits (0 
through 9), exclamation point (!), double quotation marks ("], 
dollar sign ($). percent sign {%) , ampersand (&), asostrophe 
(')♦ left parenthesis ((), right parenthesis ()), asterisk (*), 
plus sign (+), corrma (,), hyphen (-), period {.), slash (/), 
colon (:). semicolon (;), less-than sign (<), equal sign (=), 
question mark (?), and underscore (_) . 

Forming Any of the characters defined above can be used as the first 

Names character of a file or volume name. The underscore character 

can be used as a substitute for a space. If a lowercase 
alphabetic character is used, it 1s converted to Its uppercase 
counterpart ("DATA", "Data" and "data" all refer to the san»e 
file). 

Name Length The name of a tape volume can be from 1 through 6 characters in 

length. Tape file names can be from 1 through 17 characters- 
Magnetic Tape Device Pathname Construction 

As previously mentioned, magnetic tape volumes can be labeled or 
unlabeled (refer to "Magnetic Tape File Organizations" above). 

Unlabeled Tape Pathnames 

Vou must use a tape device pathname when referring to an 
unlabeled taoe. The general form of a tape device file pathname 
is: 

!oev_name 

where dev_name is the symbolic name defined for the tape device 
at system building time. 
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Labeled Tape Pathnames 

You can refer to labelec tapes either by the tape device 
pathname convention or by the tape volume id convention. 

Tape Device The tape device file pathname convention is: 

File 

!dev_name>vol_id[>f ilename] 

where dev-name is the name of the tape device as specified at 
system building time, vcl.id is the name of the tape volume, and 

-"ilenane is the name of the file on the volume. Th'5 convention 
requires that the volume be mounted on the specified device- 
Tape volume The tape volume id convention is: 
Id 

-voi_id[>f ilename] 

where vol_id is the name of the tape volume and filename is the 
name cf the file on the volume. This convention allows the 
volume to oe mounted on any available tase device. 

Automatic Magnetic Tape Volume Recognition 

Automatic volume recognition dynamical ly notes the mounting of a 
tape volume. This feature allows the File System to record the 
volume identification in a device table, thus making every tape 
volume accessible to the File System software. 

Magnetic Tape Buffering 

The -8UF argument of the Get File command can be used with 
magnetic tape files to reserve one or two buffers. If -BUF is 
not used, the File System attempts to allocate two buffers. If 
two buffers are allocated, the File System does "double 
buffering." When the tape file is oeing read, the File System 
unblocks one buffer while an anticipatory read ■* done into the 
other Duffer. Similarly, when the tape file is being written, 
the File System clocks records into one buffer while a 
previously filled block is written out of the other buffer. 
This allows application code to execute in parallel with I/O 
transfers. 
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UNIT RECORD DEVICE FILE CONVENTIONS 

Unit record devices (card readers, card punches, printers, 
terminals, and paper tape reader/punches) are used only for 
reading and writing data. They are not used for storing data, 
and thus do not require conventions for file identification and 

location. 

Unit Record Device Pathname Construction 

The pathname of a unit record oevice consists of the symbolic 
device name defined at system building time preceded oy an 
exclamation point (!). The pathname format is: 

Idev.name 

where dev_name is the symbolic device name of the unit record 
device. 

Unit Record Device Buffering 

All printers and most interactive terminals are provided with 
one File System buffer. (The operator terminal cannot be 
buffered.) By providing a File System buffer, application code 
car execute in parallel with 1/0 transfers. 

Tab Stops All printers and all terminals (except the operator terminal) 

have a tabbing capability through software that converts the tab 

into spaces. "Default tabulation stops are set at position 11 

and at every tenth position thereafter for the line length of 
the device. 



Unit Record Read Operations 

When an application task issues a logical read to a File System 
buffered device, one of the following actions occurs: 

• If the buffer is full from a prior anticipatory read, the 
data in the buffer is transferred into the application 
task's area and a physical I/O transfer (an anticipatory 
read) is performed m parallel with continued execution. 

• If the buffer is not full, task execution stalls until the 
anticipate^ read is completed. 

The timing of the initial anticipatory read performed for the 
card reader is different from that of the interactive terminals; 
for other read actions it is the same. 
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Card Reader Immediately after the Open is complete, the File System performs 
an asynchronous anticipatory read into the system buffer while 
tne application continues execution. AM Open calls are 

synchronous. 

Interactive The anticipatory read allows an application to control input 
Termina' from more than one interactive terminal, each of which 

represents a data entry terminal. By testing the status of the 
system buffer before a Reaa or by checking for the approoriate 
status return after a Read, the application will not be stalled 
4 f the terminal operator is not present at the time of the Read 
recuest. Instead, tne application can continue to poll other 
terminals. 

File Status Immediately after the Open is complete, a physical connection is 
made while the application continues execution. Depending upcn 
the language the application is written in (for example, FORTRAN 
or Assembly language), it may be able to check the status of the 
Open to see if a Read can be issued without stalling application 
execution. The File System issues an asynchronous anticipatory 
ohysical read when the status check following the physical 
connect is complete. The file status remains busy until the 
ohysical read is done and the system buffer is full. At this 
ooint, the file status is "not ousy" (the anticipatory read is 
successfully completed), and the application can issue a Read 
with tne assurance of receiving data immediately. 

Synchronous If at any point after the Open is issued, the application issues 
Read a Read before the ohysical connect anc anticipatory read have 

been completed, the Read is synchronous and further central 
processor execution is stalled on the application until the 
anticipatory -eac is comolete. 

Buffer To avoid stalling on a Read or to avoid status check looping to 

Status test the input buffer status, applications should put themselves 

in the wait state, thus making the central processor available 

for lower priority tasks. 

C03QL After the Open, an application written in COBOL must issue Read 

Programs requests. The application will be put in the wait state if it 

is executing I/O statements in synchronous mode. Otherwise, the 
COBOL run-time package performs status checks and returns a 91 
status until successful completion. The program can either loop 
on the Read or cortinue other processing. 
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Unit Record Write Operations 

A buffered write operation to a unit record device works on 
behalf of the application program in the same logical manner as 
a read operation. The program is permitted to execute in 
parallel with the physical I/O transfer to the device. To 
achieve this parallel processing, no special operation occurs on 
an Open call and no distinction is made between interactive and 
noninteractive devices. 

Status Check Each Write call is completed by moving data from the application 
buffer to the File System's buffer (performing any detabbing, if 
requested), initiating the transfer, and returning control to 
the application program. If the program performs a second Write 
while the system Puffer is still in use for a previous transfer, 
the application is stalled until the buffer is available and new 
data is moved Into it again. The application can avoid stalling 
execution when writing to an interactive terminal by doing one 
of the following: 

• Checking the status of the system buffer before issuing the 
Write to see if the interactive terminal is still in use. 

• Testing for a particular status return after the Write. 

Write with If a Write call is issued while data is being entered into the 
Reac system buffer (because of a Read), the following sequence of 

events takes place: 

• The Read is allowed to complete. 

• Input data is saved in the system buffer. 

• A synchronous Write is reissued by the File System. 

• Output data is transferred directly from the apolication 
buffer. 

Tabs Note that tab characters are not expanded into spaces. 

Erro-s If a physical I/O error occurs while data is being transferred 

from the system buffer to the device, you must be aware that the 
error occurred on the previous write operation. Furthermore, if 
any type of error occurs, the application prog-am may need to 
have saved (or oe able to retrieve) the data record so that it 
can be repeated. 
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REMOTE FILE ACCESS 

Remote file access is a File System facility that a rows 
applications to access remote data as if it were local. Remote 
objects sucn as files, volumes, magnetic tapes, and printers 
physically reside in some otner computer system (node) but, 
through remote file access, appear to be attached to your 
system. The remote file access facility captures references to 
remote objects and interfaces with the appropriate networking 
software (DSA for examole) tc get the desired function performed 
remotely. 

Statements when accessing data at another node, you may emoloy any File 

System function through macrocalls or higher-level language I/O 
statements. No special naming conventions are necessary. You 
supply the same kind of pathname you would to access local 
data. The File System checks to see if the object identified in 
the pathname is online (located on your node). If the object is 
not online, the File System checks a remote file catalog to see 
if the object is located at some other computer node. 

Commands The Remote File Catalog command is used to manage catalog 

information. This command allows a system operator or 
administrator to define, update, and display information about 
remote and local objects, nodes, and networking software. 

The Remote File Access command is used to initiate the remote 
file access facility. This command allows the system operator 
or administrator to start the facility, retrieve network status 
information, and open and close connections between nodes. 



Remote File Catalog 

Each node has its own remote file catalog to identify objects it 
can reference through remote f ; . le access. The catalog contains 
only those objects of interest to the nooe. A remote file 
catalog contains information about both remote and local 
objects. 

Remote Remote object information consists of a list of remote volumes 

Objects and devices along with the node at which they are currently 

located. The File System allows you to define your own names 
for remote objects. For example, the line printer known as 
LPT04 1n NO0E3 can be cataloged as LPT01 in N0DE1. Any 
reference to LPT01 in NODE1 will result in a search of the 
catalog and subsequent use of the printer through the remote 
file access services. The catalog can be updated dynamically Dy 
an operator or system administrator to configure new remote 
devices or to reconfigure existing ones. 
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Local Local object information consists of a list of your volumes and 

Objects devices that can be accessed from other nodes- This information 

is used by the other nodes to verify the existence of what is to 
them a remote object. It enables the File System to 
automatically update the catalog when volumes are moved from one 
system to another. 

Volume Iden- Disk volumes can be exchanged or moved from one node to another. 

tification The remote file catalog contains enough information to uniquely 
identify a remote disk volume and to recognize wher it has moved 
to another node. This Information consists of: 

• A Node of Birth (NOB) field identifying where the volume was 
originally cataloged for remote access. 

• A Oate of Birth (DOB) field identifying the date and time 
the volume was originally cataloged for remote access. 

• A Node of Residence (NOR) field identifying the node where 
the volume is currently located (cataloged as a local 
object). 

• A Node Migration Number (NMN) field identifying the number 
of times a volume has moved from one node to another. 

The remote file catalog maintains the relationship between a 
local name, its current location (NOR), and the actual name. 
When a volume is moved to another node, only its NOR is changed, 
no change is made to the local name. 

When a node connection is established, the two systems involved 
exchange local object information. A node ignores any volume 
information received that is out of date with respect to what It 
already has in its catalog. If a node has been off-line for 
some time, any old information 1t has will be discarded and any 
new information it received will be factored in. 
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Catalog Establishing a remote file catalog is usually a one-time 

Creation operation. Tne steps involved in setting up the catalog are as 

f o 1 1 ows : 

1. Create the catalog. 

You create the catalog by using the Remote File Catalog 
(RFC) command with the -CAT argument. This step is 
performed only once. 

2. Catalog a node for remote access. 

You define the nodes with which you are to communicate by 
using the RFC corrrranc with the -MODE argument. This step is 
repeated once for each node. 

3. Catalog a local object to t»e accessed remotely.. 

You define a local object that is to be accessed from other 
nodes by using the RFC command fcllowec by the local 
pathname of the object. This step is repeated once for each 
local object tc be addressed remotely. Any device to be 
catalogec must be configured on your system. A disk volume 
to oe cataloged must be mounted. 

4. Enable the remote file access facility. 

You invoke the remote file access facility by using -.he 
Remote File Access (RFA) command with the -STARTUP 
a r gument. This step configures and initializes the facility 
for communicating between nodes. It must be performed at 
the 'ocal node and each remote node whose objects are to be 
cata'oged. 

5. Establish communication with a remote node. 

You establish communication with the remote node by using 

the RFA command with the -OPEN argument. This step must 

also be performed at each remote node whose objects are to 
oe cataloged. 

6. Catalog a remote object to be accessed locally. 

You define a -emote object that is tc be accessed from your 
node by using the RFC comnand followec by the local name to 
be used to reference the object and the name of the node at 
which the object is located. If you wish tc define a local 
name that is different from the name of the object as it is 
<nown at the r emote noae, you must use the -R03J argument . 
This step is -epeated once for each remote cbject to be 
addressed loca'ly. - Note that communication must have been 
established with the remote noce thrcuoh the RFA command. 
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Initiating Remote File Access Operations 

Once a remote file catalog 1s set up, only two steps must be 
performed on a day-to-day basis before you can access remote 
devices and data (assuming that the network is up), 

1. Enable the remote file access facility. 

You and the nodes with which you are to communicate must 
issue the RFA command with the -STARTUP argument. 

2. Open the remote nodes. 

You must issue the RFA command with the -OPEN argument for 
each node with which you are to communicate. Those nodes 
that are to access objects at your node must also issue the 
RFA command with the -OPEN argument. 

After you have enabled the remote access facility and opened the 
remote nodes, you can perform any operation on the remote data 
that you would perform on local data. Whether you use system 
commands or your own application programs, the data will appear 
to be located at your node. 

Remote File Access Security 

The following paragraphs describe the way in which the remote 
file access facility handles access control, record locking, and 
data corrmitment. 

Access Access control lists define which users t)ave access to data and 

Control what kind of access they have* When files are accessed 

Lists remotely, the same level of file protection exists as when files 

are accessed locally, If a file is protected by an access 
control list, no local or remote user can access the file unless 
the user is given permission through the access control list. 

Record Record locking prevents other users from simultaneously 

Locking getting access to records that you are accessing. In many 

applications record locking involves multiple record locks on 
multiple flies and f in networking environments, may involve 
locks to multiple files 1n multiple nodes. 

A typical deadlock condition can occur if one user has locked 
some records and is trying to lock others while another user has 
these other records locked and is trying to lock the records 
already locked by the first user. The File Systerr on your 
computer node knows about the record locks on local data files 
and is able to detect deadlocks. Since the File System does not 
know about record locks on remote data files, it prevents 
deadlocks from occurring by using a time stamp algorithm. 
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Users are assigned time stamps when they start to access remote 
data. The time stamps are passed to remote noaes by the remote 
file access facility. At a remote ncae, a user may only wait 
for records that are held by younger users (users whose time 
stamp is later). If tne application attempts to lock a record 
that is already locked by an older user (a user whose time stamp 
is earlier), it receives a "deadlock has occurred" return 
status. The application must then abort, backtrack, or 
restart. If a record is held by a user who 1s local to that 
node, the local user is always considered the younger- 
Data For purposes of cata integrity, an application that accesses and 
CorTm J tment updates remote (and local) data may be structured in phases 
known as commitment units. The end of a cormiitment unit is a 
point at wnich the user is willing to commit changes to the data 
base. This type of application is said to be transaction 
oriented. It may complete successfully (commit) at a program- 
defined commitment point or it may fail (abort), in which case 
any updated data must be returned to its initial pre-transaction 
state. To ensure reliability, the transaction must either 
complete in its entirety or not complete at all. 

In remote file access, data commitments ^r^ performed in two 
phases: precommit and commit. 

• Precommit - All data *s recorded on disk with an indicator 
to show that the data is in a precommi tted state. This step 
is done locally. Remote file access then sends messages to 
precommit data at all remote nodes. 

• Commit - Once messages have been received from all affected 
remote nodes, indicating that all data is in the precommit 
state, local data is committed (unlocked and made available 
to other users). Another round of messages is then sent via 
the remote file access facility to commit data In the remote 
nodes. 

If a system or node failure occurs in any intermediate step, 
there is enough information available so that, on restart, a 
decision can be made to commit or recover the data. More 
detailed information on file recovery is presented in Section 6. 
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